home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / libs / datamaster_lib.lha / Datamaster / Developer / Autodocs / datamaster.doc
Text File  |  1997-04-27  |  60KB  |  2,073 lines
  1. TABLE OF CONTENTS
  2.  
  3. datamaster.library/--overview--
  4. datamaster.library/--Recognizer--
  5. datamaster.library/--Tags--
  6. datamaster.library/dmAddRecoDir
  7. datamaster.library/dmAddRecoFile
  8. datamaster.library/dmAddRecoName
  9. datamaster.library/dmCmpStringC
  10. datamaster.library/dmCmpStringNC
  11. datamaster.library/dmCmpTextC
  12. datamaster.library/dmCmpTextNC
  13. datamaster.library/dmCopyString
  14. datamaster.library/dmCopyStringNZ
  15. datamaster.library/dmCountString
  16. datamaster.library/dmDupString
  17. datamaster.library/dmFindStringC
  18. datamaster.library/dmFindStringNC
  19. datamaster.library/dmFindTextC
  20. datamaster.library/dmFindTextNC
  21. datamaster.library/dmFreeDMHandle
  22. datamaster.library/dmFreeRecoFile
  23. datamaster.library/dmFreeRecoList
  24. datamaster.library/dmGetDMR_Tag
  25. datamaster.library/dmGetRecoAddr
  26. datamaster.library/dmLockPrefs
  27. datamaster.library/dmMatchName
  28. datamaster.library/dmQueryRecoList
  29. datamaster.library/dmQueryRecoListNew
  30. datamaster.library/dmQueryRecoNames
  31. datamaster.library/dmQueryRecoNamesNew
  32. datamaster.library/dmReadRecoFile
  33. datamaster.library/dmRecognize
  34. datamaster.library/dmRecognizePatt
  35. datamaster.library/dmRemRecoAddr
  36. datamaster.library/dmRemRecoName
  37. datamaster.library/dmScanRecoDir
  38. datamaster.library/dmTestData
  39. datamaster.library/dmTestFile
  40. datamaster.library/dmUnLockPrefs
  41. datamaster.library/--overview--           datamaster.library/--overview--
  42.  
  43.     This library provides 2 kinds of functions:
  44.  
  45.     ° Those that really deal with recognition,recognizers/filetypes
  46.     manipulations ,etc... dmRecognize(), dmRecognizePatt(), dmTestFile()
  47.    dmTestData() ...
  48.  
  49.     ° Comparison/finding routines useable in your code,even if you don't
  50.     need any of the recognition functions.
  51.  
  52.    Every assembly programmer had to do one day string comparison and such
  53.    routines, which are trivial.
  54.  
  55.    Well here are some powerful functions like:
  56.     dmCmpStringC(),dmCmpStringNC(),dmCmpTextC(),dmCmpTextNC()
  57.     dmFindStringC(),dmFindStringNC(),dmFindTextC(),dmFindTextNC()
  58.     dmMatchName(),dmDupString(),dmCountString() ...
  59.  
  60.     ° The 'classic' convention of all libraries is of course respected:
  61.              A0/A1/D0/D1 will always be used as scratch registers.
  62. datamaster.library/--Recognizer--        datamaster.library/--Recognizer--
  63.  
  64. Some miscellaneous things you should know before making a recognizers.
  65. The main informations are in the --Tags--() section.
  66.  
  67. You will of course understand more quickly with the provided example sources.
  68.  
  69.  
  70.    * When you create a recognizer, please send it to me for inclusion to
  71.    the main package update. Sending also description of the format, and/or
  72.    the sourcecode would be nice too :)
  73.    If you want to release the recognizer "alone" in a separate archive,
  74.    stick to a "reco_CLASS-Name.lha" template,in "libs/misc" directory, so
  75.    the user can find easily the recognizers on aminet.
  76.  
  77.  
  78.     * The recognizers are 'normal' executable files.That means you can use all
  79.    the hunk types you want.
  80.  
  81.  
  82.     * The file must begin with a DATARECO macro,pointing on the taglist.
  83.     Look at --Tags--() & at the source examples.
  84.  
  85.  
  86.    * Always try to group as many Sub-FileTypes as possible under a single
  87.    Major-FileType. If you think the user can need to recognize more
  88.    precisely some Sub-FileTypes in this Major-FileType, then set the
  89.    RECOB_SubType bit in DMR_Flags, and create an array for the 
  90.    DMR_SubTypesTable tag , or use the "old" DMR_Check method, etc etc
  91.    (see example sources)
  92.  
  93.  
  94.    * The DMR_Name tag string must be as close as possible to the recognizer
  95.      FILE name (for user conveniance). (CLASS-name template)
  96.  
  97.  
  98.    * Be VERY careful when making a recognizer, and test it thoroughly, not
  99.      only with 2 or 3 files :-)
  100.      A recognizer that doesn't work correctly can miss "good" files
  101.      (annoying but not dramatical), but, WORSE, it can recognize "bad"
  102.      files. This can perturb all the others recognizers. :-(
  103.  
  104.  
  105.     * The resources the library can give you:
  106.  
  107.     Look in DatamasterBase,you have pointers on:
  108.                                             dos.library 
  109.                                             utility.library
  110.  
  111.                      & --optionally--       reqtools.library
  112.                                             (always verify if this pointer
  113.                                             is NOT NULL before using it)
  114.  
  115.                              (reqtools.library is not vital for the
  116.                              library itself,thats why it can do without)
  117.  
  118. datamaster.library/--Tags--              datamaster.library/--Tags--
  119.  
  120.  
  121.    These are the tags used in the recognizers.
  122.  
  123.    For convenience, they've been grouped by categories.
  124.  
  125.  
  126.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  127.                                 Setup flags
  128.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  129.  
  130.  
  131.     DMR_Flags    (LONG)        (MUST be present!)
  132.  
  133.         * RECOF_CheckData:
  134.              If a DMR_Check routine is available.
  135.              (or if a DMR_SubTypesTable array with 1 or more Data Check
  136.              entries is available)
  137.  
  138.         * RECOF_CheckPatt:
  139.              If a DMR_Pattern stringlist is available.
  140.              (or if a DMR_SubTypesTable array with 1 or more Patterns
  141.              entries is available)
  142.  
  143.  
  144.         * RECOF_SubType:
  145.             Means the recognizer provides Sub-FileTypes.
  146.  
  147.             If a DMR_Check tag is used, its return convention is changed to
  148.             D0 = a string pointer on the sub-filetype (or NULL if no match).
  149.  
  150.             The recognition functions will return this string in the
  151.             optionally filled dmh_SubType entry of the DM_Handle
  152.             structure.
  153.             (and the DMR_Name string in dmh_String, as usual)
  154.  
  155.             If a DMR_SubTypesTable array is used instead , set this flag
  156.             too.
  157.                 
  158.  
  159.         * RECOF_DupString:
  160.             Used with RECOB_SubType.
  161.             Means the string returned by DMR_Check is already a
  162.             dmDupString()'d one & that it'll the library's job to free it.
  163.             (the library will use this string directly in the handle in
  164.             fact:no need to dmDupString() it 'again'...everybody's happy :-)
  165.                 You should not need to use this.(very special).
  166.  
  167.     
  168.  
  169.     DMR_Name    (STRPTR)    (MUST be present!)
  170.  
  171.         Points on the MAJOR-Filetype name of this recognizer.
  172.         (remember that you may have as many recognizer files as you want,
  173.         with a same MAJOR-filetype string)
  174.  
  175.         This is the string you'll get in the dmh_String of the DM_Handle
  176.         structure returned from dmRecognize() ,dmRecognizePatt() ,
  177.         dmTestFile(), or dmTestData() if the Checkroutine routines or the
  178.         string matching is successful.
  179.  
  180.         This name is case independant,as all the strings used in the library.
  181.  
  182.         Use a "CLASS-Name" template (ASCII-Text, ANIM-FLI etc....)
  183.  
  184.         This string must be as short & simple as possible,as the user will
  185.         have to type it in in the "recognition associated actions"...So
  186.         keep the 550 chars ultra-precise descriptions for the DMR_Descr 
  187.         tag ;-)
  188.  
  189.  
  190.  
  191.     DMR_Descr    (STRPTR)    (optional) (default is "no description")
  192.  
  193.         A string giving more information about the recognized data.
  194.         Don't make it too long,maybe no one will ever read it ,& it may use
  195.         more memory than the 'useful' checkroutine/patterns ;-)
  196.  
  197.         Anyway,by convention,this description should be a zero-ended
  198.         string,with a maximal size of three 60-chars lines (separated with a
  199.         normal $A CR byte).If you want to print this description,make sure
  200.         you can handle the CR chars...If you don't,make a copy of the
  201.         string & replace the $10 chars with spaces...Of course don't even
  202.         think of modifying the original string :°]
  203.  
  204.  
  205.  
  206.     DMR_Version    (LONG)        (optional) (default is 1.0)
  207.  
  208.         Version & revision of this recognizer:
  209.  
  210.             higher word:version
  211.             lower  word:revision (2 digits max is suitable)
  212.  
  213.         asm example: DMR_version,1<<16+25    ;(= V1.25) : Ver<<16+Rev
  214.  
  215.         You get the version by a simple SWAP.
  216.  
  217.  
  218.  
  219.  
  220.     DMR_DMVersion    (LONG)        (optional) (default is 0)
  221.  
  222.         Minimal needed version of datamaster.library
  223.  
  224.         This will be checked at the initialization of the recognizer.
  225.         
  226.         The recognizer won't be added if the current datamaster.library is
  227.         not recent enough.
  228.  
  229.  
  230.  
  231.  
  232.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  233.                            The recognition tags
  234.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  235.    
  236.  
  237.    DMR_Check    (APTR)        (optional)
  238.  
  239.         Points on the checkroutine for real DATA recognition.
  240.  
  241.         INPUT:
  242.         ------
  243.         This routine will get the following registers values:
  244.  
  245.         A0=Address of data to be checked
  246.         D0=Size of data
  247.  
  248.         A2=A0    (Useful for all dmFindStringC()-like functions)
  249.         D2=D0    (===========================================)
  250.  
  251.         A5=A6= Datamaster base
  252.  
  253.  
  254.         As you can see,this gives you all you should need to get to work ;-),
  255.         & A2-D2 are already defined for any FindXXXX call you may need.
  256.  
  257.         You can trash all the registers.
  258.  
  259.         D0 does not need to be the last filled register.
  260.  
  261.  
  262.         THE ROUTINE:
  263.         ------------
  264.         In your routine,you should not modify the data you're testing.It'd be
  265.         Ok to trash a file-header allocated by dmTestFile(),that'll be
  266.         FreeMem()'d just after,but if it's data loaded by the user,& he uses
  267.         a dmRecognize() call,it would be UNBEARABLE to alter this data!!!
  268.         If you NEED to make some changes to the data,well,buffer what
  269.         you changed,& set everything as before once the test is done.
  270.  
  271.         It is highly recommanded NOT to use D0 for the comparisons such as
  272.         " move.l (a0),d0...cmp.l #magic_value,d0 ",because in such cases it's
  273.         extremely tempting to exit the check routine when the comparison is
  274.         successful (!)..the problem is that you leave with D0 set to a
  275.         perfectly unknown value!! :-() .Use D1 instead,this will force you
  276.         to think of branching to a moveq #0,d0/moveq #1,d0 somewhere at the
  277.         end of the test.
  278.         (I experienced this a few times,it's quite annoying to see your
  279.         code SHOULD work & doesn't..."Damn! It's the lib that sucks!" ;-)
  280.  
  281.  
  282.         OUTPUT:
  283.         -------
  284.         The result of the check is in D0.
  285.         Set D0 to NULL if the checking is ****SUCCESSFULL****.
  286.  
  287.         It is the same convention used in all the dmCmpXXXX(),dmFindXXXX(),
  288.         dmMatchName() calls,so you can directly exit with a valid result
  289.         when calling such library functions.
  290.  
  291.         The library will then use the name pointed by the DMR_Name tag as
  292.         MAJOR-Filetype.
  293.         
  294.  
  295.         !!VERY IMPORTANT!!
  296.         ------------------
  297.         The recognizers providing Sub-Filetypes (RECOF_SubType set in
  298.         DMR_Flags) use ANOTHER return convention. They return in d0:
  299.  
  300.                    * NULL if Failure (!!!!!)
  301.             * else the address of the Sub-Filetype string.
  302.  
  303.  
  304.  
  305.  
  306.     DMR_Pattern    (APTR)        (optional)
  307.  
  308.         Points on strings used for the Pattern-matching check.Just put the
  309.         strings one after another,and end this with a $ff byte as terminator.
  310.         DO NOT FORGET this one or a few megabytes of memory will be taken
  311.         in account :-(
  312.  
  313.         example:dc.b    "*.commodore",0
  314.                 dc.b    "*.escom",0
  315.                 dc.b    "*.viscorp",0
  316.                 dc.b    $ff
  317.  
  318.         The check will be CASE-INSENSITIVE.
  319.  
  320.         You can use the usual aliases ( see dos/ParsePatternNoCase() ) for
  321.         the patterns,but only use ONE item per string;I mean no '|' multiple
  322.         comparisons.That's not my fault!! It seems a few "|"'d strings cause
  323.         an overflow in the parse buffer.Never mind,do as explained it works
  324.         perfectly like this anyway.
  325.  
  326.  
  327.  
  328.    DMR_SubTypesTable         (APTR)          (optional)         (Lib V2+)
  329.  
  330.         If your recognizer supports Sub-filetypes, you can either use the
  331.         classic DMR_Check with "modified return convention" (RECOF_SubType
  332.         set), or use this powerful table feature.
  333.         (NOTE: This table is the only way to have subtypes with "pattern
  334.         only" checks - logical- )
  335.  
  336.         When this tag is set, it overrides DMR_Check &/or DMR_Pattern.
  337.  
  338.  
  339.         The tag points on an array of the shape:
  340.  
  341.         SubType CheckRoutine, SubType Pattern String  , SubType String
  342.    
  343.               APTR          ,           STRPTR        ,      STRPTR
  344.  
  345.  
  346.         * If a CheckRoutine or a Pattern String is not available, set the
  347.           value to -1.
  348.  
  349.         * End the array with _THREE_ NULL values...
  350.  
  351.         * Do not sort the table by alpha-order, but by priority order: the
  352.           most common sub-filetypes must be tested first.
  353.  
  354.         * Checkroutines: Return convention is like for a DMR_Check with
  355.           RECOF_SubType:   -> d0= SubType String or NULL if failure.
  356.  
  357.           This can be very useful if a SINGLE checkroutine can handle
  358.           multiple sub-filetypes: it just returns d0 = filetype. But of
  359.           course you MUST fill-in the table with the NAMES of all the
  360.           subtypes (so the user can list them!!!!)
  361.  
  362.                 example:
  363.  
  364.                 dc.l    main_check,blue_pattern,blue_name
  365.                 dc.l    main_check,red_pattern,red_name
  366.                 dc.l    main_check,yellow_pattern,yellow_name
  367.                 .....
  368.                 dc.l    0,0,0
  369.  
  370.              (see the "executable" recognizer source as example)
  371.  
  372.  
  373.          You may need a "processing" of the result of the checkroutines.
  374.          If so, use the optional DMR_CheckRoutineHook.
  375.  
  376.  
  377.         * Patterns: exactly like for DMR_Pattern...
  378.  
  379.  
  380.         So, finally everything could look like this:
  381.  
  382.                 dc.l    blue_check,-1,blue_name
  383.                 dc.l    red_check,red_pattern,red_name
  384.                 dc.l    -1,-1,yellow_name
  385.                 dc.l    -1,black_pattern,black_name
  386.                 .....
  387.                 dc.l    0,0,0
  388.  
  389.  
  390.  
  391.  
  392.    DMR_CheckRoutineHook     (APTR)
  393.  
  394.         This tag points on a personal routine of yours that will be called
  395.         each time a checkroutine of your DMR_SubTypesTable array returns
  396.         its result.
  397.  
  398.         Then you can "treat" the result if you want (for example, your
  399.         checkroutines may return d0=0 if Ok, and this hook would replace
  400.         this by the corresponding name entry of the table)
  401.  
  402.         The hook gets:
  403.                 A0= pointer on the current "line" of the array
  404.                         (checkroutine,pattern,subtype name)
  405.                 D0= value returned by the current checkroutine.
  406.  
  407.  
  408.         Sounds very complicated, it's very simple in fact.
  409.         Look at the example sources :)
  410.  
  411.         
  412.  
  413.  
  414.  
  415.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  416.                            Other important tags
  417.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  418.  
  419.     DMR_Pri           (LONG)        (optional)
  420.  
  421.         The priority is a very important parameter.The recognizers are
  422.         called by priority descending order.It is critical for speed,that
  423.         the most probable filetypes be set to a HIGH priority,leaving the
  424.         weird,slow & heavy checked types with basic or low priority.
  425.  
  426.         So please set this tag with care.
  427.  
  428.         Conventions are:
  429.  
  430.         PRI_FREQUENT
  431.         +10   :        Very common filetypes (& quickly tested,preferably!)
  432.                       (mostly system filetypes:executables,icons...)
  433.  
  434.         PRI_SINGLE
  435.         +5   :        Standard priority for 'single' filetypes.
  436.                       (by default,recognizers with DMR_RecoNumber=<1 will
  437.                       have a pri set to PRI_SINGLE)
  438.  
  439.         PRI_GROUPED
  440.         + 1   :        Standard priority for 'grouped' filetypes.
  441.                       (by default,recognizers with DMR_RecoNumber>1 will
  442.                       have a pri set to PRI_GROUPED)
  443.                       
  444.         PRI_GROUPEDSLOW
  445.         -5   :        'Grouped' filetypes having heavy checking routines.
  446.  
  447.         PRI_RARE
  448.         -10   :        Rare filetypes (or very slowly tested)
  449.  
  450.  
  451.         PRI_HOOKNAME
  452.         -100  :        Set by the library, automatically, for recognizers
  453.                        having a DMR_HookName tag.
  454.  
  455.  
  456.    Note: Don't forget that if you omit this tag (or set it to zero!!), the
  457.          library will give it a PRI_SINGLE or PRI_GROUPED priority after
  458.          having checked the number of subtypes (it will count the number of
  459.          entries in the DMR_SubTypesTable array)
  460.  
  461.  
  462.  
  463.  
  464.    DMR_InitRoutine      (APTR)         (optional)
  465.  
  466.              Points on an initialization routine that will be called when
  467.              the recognizer is loaded & added to the list.
  468.  
  469.              If you need any resource opening (libraries etc),do it here!
  470.  
  471.              WARNING:this routine must use the 'standard' resource opening
  472.              conventions,that's to say return a non-NULL value if
  473.              everything went fine.
  474.  
  475.  
  476.  
  477.    DMR_ExitRoutine      (APTR)         (optional)
  478.  
  479.              Free all the allocated resources here.This function will be
  480.              called when the recognizer is removed from list.
  481.  
  482.  
  483.  
  484.  
  485.   DMR_Class             (LONG)  (optional) (default is DMCLASSF_Unknown)
  486.                                                                 (Lib V2+)
  487.  
  488.         The class concept is not used for the moment, but I plan to use
  489.         this as "filtering" option in the future.
  490.         So please define correctly this tag.
  491.  
  492.  
  493.         Here are the current classes for the moment:
  494.  
  495.  
  496.                    DMCLASSF_UNKNOWN
  497.                    DMCLASSF_GRAPHICS
  498.                    DMCLASSF_ANIMATION
  499.                    DMCLASSF_MUSIC
  500.                    DMCLASSF_SAMPLE
  501.                    DMCLASSF_PACKED
  502.                    DMCLASSF_SYSTEM
  503.                    DMCLASSF_MISC
  504.                    DMCLASSF_LINK
  505.                    DMCLASSF_ASCII
  506.  
  507.  
  508.  
  509.    DMR_HookName         (STRPTR)                        (Lib V2+)
  510.  
  511.         This is a rather special feature.
  512.  
  513.         The ti_data of this tag points on a "target" recognizer name.
  514.  
  515.         Some explanations, with an example.
  516.  
  517.         I needed this tag as I wanted to recognize "CUST" and "RonKlaren"
  518.         music formats. The problem was that such musics are EXECUTABLE
  519.         files (with internal replayer).
  520.  
  521.         The "Executable" recognizer has a PRI_FREQUENT priority, which is
  522.         quite normal. So all the CUST/RK musics were recognized as
  523.         executables! The only solution would have been to give the recognizer
  524.         checking these formats a priority higher than the "executable" one.
  525.  
  526.         But this was NOT acceptable : Executables are frequent, CUST & RK
  527.         are definetely NOT. Why slow down all the checks for such rare
  528.         formats? NO...
  529.  
  530.         So here is the solution I came out with: A kind of "2nd chance",
  531.         with this HookName tag. Such recognizers can make a "HOOK" on a
  532.         target filetype. (here :"executable").
  533.         NOTE: I talk of MAJOR-filetype (i.e. the one of DMR_Name tag)
  534.  
  535.  
  536.         What happens then?
  537.         ~~~~~~~~~~~~~~~~~~
  538.  
  539.         In our example...
  540.         Each time some data is recognized as "executable", the library will
  541.         scan the recognizers list, for recognizers with a lower priority,
  542.         searching for those with 'DMR_HookName=Executable'. They will be
  543.         tested in turn, and if one succeeds, it will "steal" the
  544.         recognition from the "target" recognizer (executable here)
  545.  
  546.         The big advantage is that this "special check" is only made when
  547.         the data is recognized as executable, NOT for just any check.
  548.         
  549.         (-: I hope all this was clear enough :-)        
  550.  
  551.  
  552.         About those recognizers
  553.         ~~~~~~~~~~~~~~~~~~~~~~~
  554.         - They are exactly as other recognizers. No difference.
  555.  
  556.         - Their priority is automatically set to PRI_HOOKNAME (-100).
  557.           (this is just before the Generic recognizer (-120) )
  558.  
  559.  
  560.      
  561.  
  562.  
  563.  
  564. datamaster.library/dmAddRecoDir           datamaster.library/dmAddRecoDir
  565.  
  566.    NAME
  567.     dmAddRecoDir -- Adds the RECOGNIZERS of specified Dir to list.
  568.  
  569.    SYNOPSIS
  570.     result = dmAddRecoDir( DirName );
  571.     D0               A0
  572.  
  573.     ULONG dmAddRecoDir( STRPTR DirName );
  574.  
  575.    FUNCTION
  576.     Loads/adds all the recognizers present in the dir (no subdirs
  577.     support)
  578.  
  579.    INPUTS
  580.     DirName - Directory Path (may be NULL,so default LIBS:Recognizers/
  581.         will be used)
  582.  
  583.    RESULT
  584.     result (D0) - NULL if failure
  585.  
  586.    NOTE
  587.     ° No need to use a pair of dmLockPrefs() / dmUnLockPrefs()
  588.  
  589.     ° As datamaster.library accepts more than one recognizer per FILETYPE
  590.     definition, you may reload the same RECOGNIZER as many times as you
  591.     want,the problem being that it WON'T *REPLACE* the previous one,it
  592.     will be ADDED as if it was some kind of complement (which is the aim
  593.     of this ;-).So this function is useful mainly to add facultative
  594.     groups (recognizers/Store/ for example);
  595.  
  596.     Using it 10 times on the same dir will just lead to have 10 times the
  597.     same recognizers in memory,10 times slower etc....  ;-(
  598.  
  599.    BUGS
  600.     No bugs.I just plan in the future to make a kind of checksum to
  601.     recognize (!) the recognizers,& avoid this double-loading.(as they
  602.     can't be distinguished from their filetype name..it's the
  603.     same,yes,but it's licit!!!)
  604.  
  605.    SEE ALSO
  606.     dmScanRecoDir()
  607.  
  608. datamaster.library/dmAddRecoFile         datamaster.library/dmAddRecoFile
  609.  
  610.    NAME
  611.     dmAddRecoFile -- Adds a RECOGNIZER to list.
  612.  
  613.    SYNOPSIS
  614.     Recognizer = dmAddRecoFile( FileName );
  615.     D0                A0
  616.  
  617.     ULONG dmAddRecoFile( STRPTR FileName );
  618.  
  619.    FUNCTION
  620.     Loads/adds the given recognizer file.
  621.  
  622.    INPUTS
  623.     FileName - well,just a filename you know...  (Default path is set to
  624.         LIBS:Recognizers/ )
  625.  
  626.    RESULT
  627.     Recognizer (D0) - Address of the loaded segment (REAL addr,NOT BCPL).
  628.         Returns NULL if error.
  629.  
  630.    NOTE
  631.     ° No need to use a pair of dmLockPrefs() / dmUnLockPrefs()
  632.  
  633.     ° As datamaster.library accepts more than one recognizer per FILETYPE
  634.     definition, you may reload the same RECOGNIZER as many times as you
  635.     want,the problem being that it WON'T *REPLACE* the previous one,it
  636.     will be ADDED as if it were some kind of complement (which is the aim
  637.     of this ;-).
  638.  
  639.     [Same remark as in dmAddRecoDir()]
  640.  
  641.    BUGS
  642.     See dmAddRecoDir()
  643.  
  644.    SEE ALSO
  645.     dmAddRecoDir(),dmReadRecoFile(),dmAddRecoName(),dmRemRecoAddr()
  646.  
  647. datamaster.library/dmAddRecoName         datamaster.library/dmAddRecoName
  648.  
  649.    NAME
  650.     dmAddRecoName -- Adds a FILETYPE to memorylist.
  651.  
  652.    SYNOPSIS
  653.     result = dmAddRecoName( RecoName );
  654.     D0            A0
  655.  
  656.     ULONG dmAddRecoName( STRPTR RecoName );
  657.  
  658.    FUNCTION
  659.     Loads/adds all the recognizers files beginning with such a name.
  660.  
  661.    INPUTS
  662.     RecoName - Not really a filename.This is a FILETYPE name,which means
  663.         possibly more than one *file* will match this.    for
  664.         instance:"Dummy" as parameter would add
  665.         "Dummy.patt","Dummy.data","Dummy.mylittleAddedDefinitions"
  666.         etc..  (Default path is set to LIBS:Recognizers/ )
  667.  
  668.    RESULT
  669.     result (D0) - NULL if error.
  670.  
  671.    NOTE
  672.     ° No need to use a pair of dmLockPrefs() / dmUnLockPrefs()
  673.  
  674.     ° Same remark as in dmAddRecoDir() etc...  for double-loading.
  675.  
  676.    BUGS
  677.     see dmAddRecoDir()
  678.  
  679.    SEE ALSO
  680.     dmRemRecoName()
  681.  
  682. datamaster.library/dmCmpStringC           datamaster.library/dmCmpStringC
  683.  
  684.    NAME
  685.     dmCmpStringC -- Support function
  686.  
  687.    SYNOPSIS
  688.     result, address = dmCmpStringC( UserString, RefString );
  689.     D0    A1            A0        A1
  690.  
  691.     ULONG dmCmpStringC( STRPTR UserString, STRPTR RefString );
  692.  
  693.    FUNCTION
  694.     Compares string with the reference string ,case dependent.
  695.  
  696.     Every programmer had one day to make such trivial routines.So here
  697.     are they,once for all...
  698.  
  699.    INPUTS
  700.     UserString - String to be compared.
  701.  
  702.     RefString - Reference string to match.
  703.  
  704.    RESULT
  705.     result (D0) - returns zero **IF MATCHES** (may seem not so
  706.         conventional but it's logical if you think it in
  707.         assembler..."BEQ" happens when the Zero bit of the CCR is
  708.         set...) note:if matching fails,A0 will be preserved.
  709.  
  710.     address (A1) - (asm users only) if matches,points just after the
  711.         found data
  712.  
  713.    SEE ALSO
  714.     dmCmpStringNC(),dmFindStringC(),dmCmpTextC()
  715.  
  716. datamaster.library/dmCmpStringNC         datamaster.library/dmCmpStringNC
  717.  
  718.    NAME
  719.     dmCmpStringNC -- Support function
  720.  
  721.    SYNOPSIS
  722.     result, address = dmCmpStringNC( UserString, RefString );
  723.     D0    A1             A0         A1
  724.  
  725.     ULONG dmCmpStringNC( STRPTR UserString, STRPTR RefString );
  726.  
  727.    FUNCTION
  728.     Compares string with the reference string ,case independent.
  729.  
  730.     Every programmer had one day to make such trivial routines.So here
  731.     are they,once for all...
  732.  
  733.    INPUTS
  734.     UserString - String to be compared.
  735.  
  736.     RefString - Reference string to match.
  737.  
  738.    RESULT
  739.     result (D0) - returns zero **IF MATCHES** (may seem not so
  740.         conventional but it's logical if you think it in
  741.         assembler..."BEQ" happens when the Zero bit of the CCR is
  742.         set...) note:if matching fails,A0 will be preserved.
  743.  
  744.     address (A1) - (asm users only) if matches,points just after the
  745.         found data
  746.  
  747.    SEE ALSO
  748.     dmCmpStringC(),dmFindStringNC(),dmCmpTextNC()
  749.  
  750. datamaster.library/dmCmpTextC            datamaster.library/dmCmpTextC
  751.  
  752.    NAME
  753.     dmCmpTextC -- Support function
  754.  
  755.    SYNOPSIS
  756.     result, address = dmCmpTextC( UserString, RefString );
  757.     D0    A1              A0      A1
  758.  
  759.     ULONG dmCmpTextC( APTR UserString, STRPTR RefString );
  760.  
  761.    FUNCTION
  762.     Compares text with the reference string ,case dependent.
  763.  
  764.     For example: "HelloWorld" TEXT would match "Hello" string.
  765.  
  766.     Every programmer had one day to make such trivial routines.So here
  767.     are they,once for all...
  768.  
  769.    INPUTS
  770.     UserString - text to be compared.
  771.  
  772.     RefString - Reference string to match.
  773.  
  774.    RESULT
  775.     result (D0) - returns zero **IF MATCHES** (may seem not so
  776.         conventional but it's logical if you think it in
  777.         assembler..."BEQ" happens when the Zero bit of the CCR is
  778.         set...) note:if matching fails,A0 will be preserved.
  779.  
  780.     address (A1) - (asm users only) if matches,points just after the
  781.         found data
  782.  
  783.    SEE ALSO
  784.     dmCmpTextNC(),dmFindTextC(),dmCmpStringC()
  785.  
  786. datamaster.library/dmCmpTextNC               datamaster.library/dmCmpTextNC
  787.  
  788.    NAME
  789.     dmCmpTextNC -- Support function
  790.  
  791.    SYNOPSIS
  792.     result, address = dmCmpTextNC( UserString, RefString );
  793.     D0    A1               A0       A1
  794.  
  795.     ULONG dmCmpTextNC( APTR UserString, STRPTR RefString );
  796.  
  797.    FUNCTION
  798.     Compares text with the reference string ,case independent.
  799.  
  800.     For example: "heLLOWorld" TEXT would match "hELlo" string.
  801.  
  802.     Every programmer had one day to make such trivial routines.So here
  803.     are they,once for all...
  804.  
  805.    INPUTS
  806.     UserString - text to be compared.
  807.  
  808.     RefString - Reference string to match.
  809.  
  810.    RESULT
  811.     result (D0) - returns zero **IF MATCHES** (may seem not so
  812.         conventional but it's logical if you think it in
  813.         assembler..."BEQ" happens when the Zero bit of the CCR is
  814.         set...) note:if matching fails,A0 will be preserved.
  815.  
  816.     address (A1) - (asm users only) if matches,points just after the
  817.         found data
  818.  
  819.    SEE ALSO
  820.     dmCmpTextC(),dmFindTextNC(),dmCmpStringNC()
  821.  
  822. datamaster.library/dmCopyString           datamaster.library/dmCopyString
  823.  
  824.    NAME
  825.     dmCopyString -- Support function
  826.  
  827.    SYNOPSIS
  828.     LastByte = dmCopyString( UserString, Dest );
  829.     A0             A0         A1
  830.  
  831.     APTR dmCopyString( STRPTR UserString, APTR Dest );
  832.  
  833.    FUNCTION
  834.     A simple copystring routine that's all...  (wow! a 4 instructions
  835.     routine ;-)
  836.  
  837.     (it includes the final zero of the string)
  838.  
  839.     Just another trivial routine...
  840.  
  841.    INPUTS
  842.     UserString - String to be copied
  843.  
  844.     Dest - Address where to copy the string
  845.  
  846.    RESULT
  847.     LastByte (A0) - Points on the byte following the last
  848.         character.(that's to say on the zero byte).Handy if you want
  849.         to stick another string after this one.
  850.  
  851.    SEE ALSO
  852.     dmCopyStringNZ(),dmDupString(),dmCountString()
  853.  
  854. datamaster.library/dmCopyStringNZ        datamaster.library/dmCopyStringNZ
  855.  
  856.    NAME
  857.     dmCopyStringNZ -- Support function
  858.  
  859.    SYNOPSIS
  860.     LastByte = dmCopyStringNZ( UserString, Dest );
  861.     A0               A0           A1
  862.  
  863.     APTR dmCopyStringNZ( STRPTR UserString, APTR Dest );
  864.  
  865.    FUNCTION
  866.     A simple copystring routine that's all...  (wow! a 4 instructions
  867.     routine ;-)
  868.  
  869.     (it DOES NOT include the final zero of the string)
  870.  
  871.     Just another trivial routine...
  872.  
  873.    INPUTS
  874.     UserString - String to be copied
  875.  
  876.     Dest - Address where to copy the string
  877.  
  878.    RESULT
  879.     LastByte (A0) - Points on the byte following the last character.Handy
  880.         if you want to stick another string after this one.
  881.  
  882.    SEE ALSO
  883.     dmCopyString(),dmDupString(),dmCountString()
  884.  
  885. datamaster.library/dmCountString         datamaster.library/dmCountString
  886.  
  887.    NAME
  888.     dmCountString -- Support function
  889.  
  890.    SYNOPSIS
  891.     result = dmCountString( UserString );
  892.     D0            A0
  893.  
  894.     ULONG dmCountString( STRPTR UserString );
  895.  
  896.    FUNCTION
  897.     Counts the number of characters in the string.
  898.  
  899.     Just another trivial routine...
  900.  
  901.    INPUTS
  902.     UserString - String to 'count'
  903.  
  904.    RESULT
  905.     result (D0) - size of the string in bytes (NOT including the final
  906.         zero)
  907.  
  908.    SEE ALSO
  909.     dmCopyString(),dmCopyStringNZ(),dmDupString()
  910.  
  911. datamaster.library/dmDupString               datamaster.library/dmDupString
  912.  
  913.    NAME
  914.     dmDupString -- Support function
  915.  
  916.    SYNOPSIS
  917.     StringAddress, StringSize = dmDupString( UserString );
  918.     A0           D0             A0
  919.  
  920.     APTR dmDupString( STRPTR UserString );
  921.  
  922.    FUNCTION
  923.     A nice function for lazy people like me...It takes your string,gets
  924.     it size, (INCLUDING THE ZERO) allocates the space for it,& copies it
  925.     there...
  926.  
  927.     It can be of some help if you want to do a dmCmpStringNC()-like
  928.     call,but need to modify a bit the string...just duplicate it & work
  929.     on the copy...
  930.  
  931.    INPUTS
  932.     UserString - String to be copied
  933.  
  934.    RESULT
  935.     StringAddress (A0) - Allocated Address (or NULL if failure)
  936.  
  937.     StringSize (D0) - (asm users only) Size allocated for the string.Pass
  938.         this to Exec/FreeMem() when done.Will be NULL is failure.
  939.  
  940.    NOTE
  941.     Don't forget to FreeMem() the string when done,of course..  ;-)
  942.  
  943.    SEE ALSO
  944.     dmCopyString(),dmCopyStringNZ(),dmCountString()
  945.  
  946. datamaster.library/dmFindStringC         datamaster.library/dmFindStringC
  947.  
  948.    NAME
  949.     dmFindStringC -- Support function
  950.  
  951.    SYNOPSIS
  952.     result = dmFindStringC( StartAddress, RefString, ScanSize,
  953.     D0            A0          A1     D0
  954.         DataStart, DataSize );
  955.         A2           D2
  956.  
  957.     ULONG dmFindStringC( APTR StartAddress, STRPTR RefString, ULONG
  958.         ScanSize, APTR DataStart, ULONG DataSize );
  959.  
  960.    FUNCTION
  961.     Finds a String (case sensitive) in a memory zone,starting at a
  962.     particular address.
  963.  
  964.     Note:finding a STRING means it must have a FINAL ZERO.This is much
  965.     less common then TEXT finding I think.
  966.  
  967.     Every programmer had one day to make such trivial routines.So here
  968.     are they,once for all...
  969.  
  970.    INPUTS
  971.     StartAddress - Current address to start finding.
  972.  
  973.     RefString - Reference string to find.
  974.  
  975.     ScanSize - Size of scanning (-1 means all data).StartAddress &
  976.         Scansize values will be automatically maintained within the
  977.         bounds of DataStart->DataStart+DataSize.  example:
  978.         FindStringC(15000,refstring,5000,10000,8000).Here you can see
  979.         that Scanzone is 15000->20000 whereas Datazone is
  980.         10000->18000.So Scanzone will be cut to 15000->18000.
  981.  
  982.     DataStart - Address of the data zone we're searching in.Of course
  983.         DataStart<StartAddress<DataStart+DataSize.
  984.  
  985.     DataSize - Size of the data zone.
  986.  
  987.    RESULT
  988.     result (D0) - returns zero **IF FOUND** (may seem not so conventional
  989.         but it's logical if you think it in assembler..."BEQ" happens
  990.         when the Zero bit of the CCR is set...).In that case,you
  991.         would also get A1 pointing immediately after the found data.
  992.         Anyway,you will get a0 (StartAddress) preserved.
  993.  
  994.    SEE ALSO
  995.     dmFindStringNC(),dmFindTextC(),dmCmpStringC()
  996.  
  997. datamaster.library/dmFindStringNC        datamaster.library/dmFindStringNC
  998.  
  999.    NAME
  1000.     dmFindStringNC -- Support function
  1001.  
  1002.    SYNOPSIS
  1003.     result = dmFindStringNC( StartAddress, RefString, ScanSize,
  1004.     D0             A0           A1      D0
  1005.         DataStart, DataSize );
  1006.         A2           D2
  1007.  
  1008.     ULONG dmFindStringNC( APTR StartAddress, STRPTR RefString, ULONG
  1009.         ScanSize, APTR DataStart, ULONG DataSize );
  1010.  
  1011.    FUNCTION
  1012.     Finds a String (case insensitive) in a memory zone,starting at a
  1013.     particular address.
  1014.  
  1015.     Note:finding a STRING means it must have a FINAL ZERO.This is much
  1016.     less common then TEXT finding I think.
  1017.  
  1018.     Every programmer had one day to make such trivial routines.So here
  1019.     are they,once for all...
  1020.  
  1021.    INPUTS
  1022.     StartAddress - Current address to start finding.
  1023.  
  1024.     RefString - Reference string to find.
  1025.  
  1026.     ScanSize - Size of scanning (-1 means all data).StartAddress &
  1027.         Scansize values will be automatically maintained within the
  1028.         bounds of DataStart->DataStart+DataSize.  example:
  1029.         FindStringNC(15000,refstring,5000,10000,8000).Here you can
  1030.         see that Scanzone is 15000->20000 whereas Datazone is
  1031.         10000->18000.So Scanzone will be cut to 15000->18000.
  1032.  
  1033.     DataStart - Address of the data zone we're searching in.Of course
  1034.         DataStart<StartAddress<DataStart+DataSize.
  1035.  
  1036.     DataSize - Size of the data zone.
  1037.  
  1038.    RESULT
  1039.     result (D0) - returns zero **IF FOUND** (may seem not so conventional
  1040.         but it's logical if you think it in assembler..."BEQ" happens
  1041.         when the Zero bit of the CCR is set...).In that case,you
  1042.         would also get A1 pointing immediately after the found data.
  1043.         Anyway,you will get a0 (StartAddress) preserved.
  1044.  
  1045.    SEE ALSO
  1046.     dmFindStringC(),dmFindTextNC(),dmCmpStringNC()
  1047.  
  1048. datamaster.library/dmFindTextC               datamaster.library/dmFindTextC
  1049.  
  1050.    NAME
  1051.     dmFindTextC -- Support function
  1052.  
  1053.    SYNOPSIS
  1054.     result = dmFindTextC( StartAddress, RefString, ScanSize,
  1055.     D0              A0        A1           D0
  1056.         DataStart, DataSize );
  1057.         A2           D2
  1058.  
  1059.     ULONG dmFindTextC( APTR StartAddress, STRPTR RefString, ULONG
  1060.         ScanSize, APTR DataStart, ULONG DataSize );
  1061.  
  1062.    FUNCTION
  1063.     Finds a Text (case sensitive) in a memory zone,starting at a
  1064.     particular address.
  1065.  
  1066.     Note:a 'TEXT' is a 'string' WITHOUT A FINAL ZERO.
  1067.  
  1068.     Every programmer had one day to make such trivial routines.So here
  1069.     are they,once for all...
  1070.  
  1071.    INPUTS
  1072.     StartAddress - Current address to start finding.
  1073.  
  1074.     RefString - Reference string to find.
  1075.  
  1076.     ScanSize - Size of scanning (-1 means all data).StartAddress &
  1077.         Scansize values will be automatically maintained within the
  1078.         bounds of DataStart->DataStart+DataSize.  example:
  1079.         FindTextC(15000,refstring,5000,10000,8000).Here you can see
  1080.         that Scanzone is 15000->20000 whereas Datazone is
  1081.         10000->18000.So Scanzone will be cut to 15000->18000.
  1082.  
  1083.     DataStart - Address of the data zone we're searching in.Of course
  1084.         DataStart<StartAddress<DataStart+DataSize.
  1085.  
  1086.     DataSize - Size of the data zone.
  1087.  
  1088.    RESULT
  1089.     result (D0) - returns zero **IF FOUND** (may seem not so conventional
  1090.         but it's logical if you think it in assembler..."BEQ" happens
  1091.         when the Zero bit of the CCR is set...).In that case,you
  1092.         would also get A1 pointing immediately after the found data.
  1093.         Anyway,you will get a0 (StartAddress) preserved.
  1094.  
  1095.    SEE ALSO
  1096.     dmFindTextNC(),dmFindStringC(),dmCmpTextC()
  1097.  
  1098. datamaster.library/dmFindTextNC           datamaster.library/dmFindTextNC
  1099.  
  1100.    NAME
  1101.     dmFindTextNC -- Support function
  1102.  
  1103.    SYNOPSIS
  1104.     result = dmFindTextNC( StartAddress, RefString, ScanSize,
  1105.     D0               A0         A1     D0
  1106.         DataStart, DataSize );
  1107.         A2           D2
  1108.  
  1109.     ULONG dmFindTextNC( APTR StartAddress, STRPTR RefString, ULONG
  1110.         ScanSize, APTR DataStart, ULONG DataSize );
  1111.  
  1112.    FUNCTION
  1113.     Finds a Text (case insensitive) in a memory zone,starting at a
  1114.     particular address.
  1115.  
  1116.     Note:a 'TEXT' is a 'string' WITHOUT A FINAL ZERO.
  1117.  
  1118.     Every programmer had one day to make such trivial routines.So here
  1119.     are they,once for all...
  1120.  
  1121.    INPUTS
  1122.     StartAddress - Current address to start finding.
  1123.  
  1124.     RefString - Reference string to find.
  1125.  
  1126.     ScanSize - Size of scanning (-1 means all data).StartAddress &
  1127.         Scansize values will be automatically maintained within the
  1128.         bounds of DataStart->DataStart+DataSize.  example:
  1129.         FindTextNC(15000,refstring,5000,10000,8000).Here you can see
  1130.         that Scanzone is 15000->20000 whereas Datazone is
  1131.         10000->18000.So Scanzone will be cut to 15000->18000.
  1132.  
  1133.     DataStart - Address of the data zone we're searching in.Of course
  1134.         DataStart<StartAddress<DataStart+DataSize.
  1135.  
  1136.     DataSize - Size of the data zone.
  1137.  
  1138.    RESULT
  1139.     result (D0) - returns zero **IF FOUND** (may seem not so conventional
  1140.         but it's logical if you think it in assembler..."BEQ" happens
  1141.         when the Zero bit of the CCR is set...).In that case,you
  1142.         would also get A1 pointing immediately after the found data.
  1143.         Anyway,you will get a0 (StartAddress) preserved.
  1144.  
  1145.    SEE ALSO
  1146.     dmFindTextC(),dmFindStringNC(),dmCmpTextNC()
  1147.  
  1148. datamaster.library/dmFreeDMHandle        datamaster.library/dmFreeDMHandle
  1149.  
  1150.    NAME
  1151.     dmFreeDMHandle -- Free a handle
  1152.  
  1153.    SYNOPSIS
  1154.     dmFreeDMHandle( Handle );
  1155.             A0
  1156.  
  1157.     VOID dmFreeDMHandle( APTR Handle );
  1158.  
  1159.    FUNCTION
  1160.     For now,the DM_Handle structure consists mostly of the filetype
  1161.     string & size.
  1162.  
  1163.     This function frees the string itself from memory,& the handle
  1164.     structure.
  1165.  
  1166.    INPUTS
  1167.     Handle - Handle allocated via dmRecognize(),dmRecognizePatt() or
  1168.         dmTestFile().  a NULL value is accepted,for exiting on error
  1169.         [a failed dmRecognize() etc...]
  1170.  
  1171.    RESULT
  1172.  
  1173.    SEE ALSO
  1174.     dmRecognize(),dmRecognizePatt(),dmTestFile()
  1175.  
  1176. datamaster.library/dmFreeRecoFile        datamaster.library/dmFreeRecoFile
  1177.  
  1178.    NAME
  1179.     dmFreeRecoFile -- Frees data given back by dmReadRecoFile()
  1180.  
  1181.    SYNOPSIS
  1182.     dmFreeRecoFile( SegAddr );
  1183.             A0
  1184.  
  1185.     VOID dmFreeRecoFile( APTR SegAddr );
  1186.  
  1187.    FUNCTION
  1188.     It's more or less an UnLoadSeg...
  1189.  
  1190.    INPUTS
  1191.     SegAddr - Address of the segment loaded via dmReadRecoFile().  May be
  1192.         zero.
  1193.  
  1194.    RESULT
  1195.  
  1196.    BUGS
  1197.     None known
  1198.  
  1199.    WARNING
  1200.     Careful!!! Of course,you must ***NOT*** use dmRemRecoAddr()
  1201.     here!!!!!!
  1202.  
  1203.    SEE ALSO
  1204.     dmReadRecoFile()
  1205.  
  1206. datamaster.library/dmFreeRecoList        datamaster.library/dmFreeRecoList
  1207.  
  1208.    NAME
  1209.     dmFreeRecoList -- Free a RecoList
  1210.  
  1211.    SYNOPSIS
  1212.     dmFreeRecoList( RecoList );
  1213.             A0
  1214.  
  1215.     VOID dmFreeRecoList( Struct RecoList *RecoList );
  1216.  
  1217.    INPUTS
  1218.     RecoList - RecoList got from dmQueryRecoListNew() or
  1219.         dmQueryRecoNamesNew() a NULL value is accepted,for exiting on
  1220.         error
  1221.  
  1222.    RESULT
  1223.  
  1224.    SEE ALSO
  1225.     dmQueryRecoListNew(),dmQueryRecoNamesNew()
  1226.  
  1227. datamaster.library/dmGetDMR_Tag           datamaster.library/dmGetDMR_Tag
  1228.  
  1229.    NAME
  1230.     dmGetDMR_Tag -- Extract a DMR_ Tag value of a recognizer.
  1231.  
  1232.    SYNOPSIS
  1233.     value = dmGetDMR_Tag( Recognizer, DMR_ tag );
  1234.     D0              A0      A1
  1235.  
  1236.     ULONG dmGetDMR_Tag( APTR Recognizer, ULONG DMR_ tag );
  1237.  
  1238.    FUNCTION
  1239.     This function finds the taglist in the recognizer,& performs a kind
  1240.     of GetTagData().It will set some tags to particular defaults
  1241.  
  1242.     Such settings are important for the library's optimal behavior,so do
  1243.     not try to get some information by your own means,such as
  1244.     GetTagdata().
  1245.  
  1246.    INPUTS
  1247.     Recognizer - Address of the recognizer segment.
  1248.  
  1249.     DMR_ tag - A ti_tag to find.See definitions in libraries/datamaster.i
  1250.  
  1251.    RESULT
  1252.     value (D0) - ti_data of the tag
  1253.  
  1254.    WARNING
  1255.     You MUST use a dmLockPrefs() before calling this & an dmUnLockPrefs()
  1256.     when you finished using the information you got.
  1257.  
  1258.    BUGS
  1259.     None known
  1260.  
  1261. datamaster.library/dmGetRecoAddr         datamaster.library/dmGetRecoAddr
  1262.  
  1263.    NAME
  1264.     dmGetRecoAddr -- Get ADDRESS of a RECOGNIZER,given its name.
  1265.  
  1266.    SYNOPSIS
  1267.     recognizer = dmGetRecoAddr( Filetype, CurrentAddr );
  1268.     D0                A0          A1
  1269.  
  1270.     APTR dmGetRecoAddr( STRPTR Filetype, APTR CurrentAddr );
  1271.  
  1272.    FUNCTION
  1273.     When you have a FILETYPE name ,got by dmQueryRecoNamesNew() for
  1274.     instance,you may want to know how many RECOGNIZERS there are behind
  1275.     this single name,& also what they 'look' like (tag-analyzing,info
  1276.     printing...).
  1277.  
  1278.     This function gives you back the 'current' recognizer corresponding
  1279.     to the filetype,skipping all those already found in previous calls
  1280.     (you have the CurrentAddr that indicates where we got so far).
  1281.  
  1282.    INPUTS
  1283.     Filetype - Name of the Filetype to find.
  1284.  
  1285.     CurrentAddr - Address of the first entry matching the name,to start
  1286.         with.  (very easy you'll see what I mean soon
  1287.         :).Typically,you should set this to zero to find the 1st
  1288.         RECOGNIZER matching this FILETYPE (as already said,one
  1289.         filetype may be split in various recognizers).Then,to find
  1290.         ALL the recognizers corresponding to the Filetype,just use
  1291.         the Address returned by the function in the next call,til it
  1292.         returns zero (last one).
  1293.  
  1294.    RESULT
  1295.     recognizer (D0) - Address of the recognizer,or zero if it was the
  1296.         last one (or no recognizer at all).
  1297.  
  1298.    EXAMPLE
  1299.     ;extracted & modified from DMcontrol.s
  1300.  
  1301.     CALLDM dmLockPrefs
  1302.  
  1303.     ...
  1304.  
  1305.     lea    name,a0
  1306.     sub.l    a1,a1
  1307.     CALLDM    dmGetRecoAddr
  1308.     tst.l    d0
  1309.     beq    do_NOTFOUND
  1310.  
  1311.     .another:
  1312.     move.l    d0,a0
  1313.     bsr    PrintUnit
  1314.  
  1315.     lea    name,a0
  1316.     move.l    d0,a1
  1317.     CALLDM    dmGetRecoAddr
  1318.     tst.l    d0
  1319.     bne.s    .another
  1320.  
  1321.     CALLDM dmUnLockPrefs
  1322.  
  1323.     ...
  1324.  
  1325.    WARNING
  1326.     You MUST use a dmLockPrefs() before calling this & an dmUnLockPrefs()
  1327.     when you finished using the Address you got.
  1328.  
  1329.    BUGS
  1330.     In V1, this function blew up (!) if the current recognizer was
  1331.     RemRecoAddr()'ed between two calls.  (I had forgotten to handle this,
  1332.     so there was an endless search in table :-(
  1333.  
  1334.    SEE ALSO
  1335.     dmRemRecoAddr(),dmRemRecoName()
  1336.  
  1337. datamaster.library/dmLockPrefs               datamaster.library/dmLockPrefs
  1338.  
  1339.    NAME
  1340.     dmLockPrefs -- Indicate that user is using info on recognizers.
  1341.  
  1342.    SYNOPSIS
  1343.     void = dmLockPrefs( void );
  1344.                 
  1345.  
  1346.     VOID dmLockPrefs( VOID void );
  1347.  
  1348.    FUNCTION
  1349.     Increases by one the dmb_LockNest counter of
  1350.     DatamasterBase,indicating that one more user reads/uses informations
  1351.     in the recognizers,mainly reading the tags.
  1352.  
  1353.     Locking the preferences prevents the removal (& addition) of the
  1354.     recognizers,so you can get information safely from the
  1355.     tags,recognizers namelists etc...
  1356.  
  1357.     It is used internally when recognition functions ( dmRecognize() etc
  1358.     ) are working,and you MUST use it when dealing with functions like
  1359.     dmQueryRecoListNew() ,dmQueryRecoName().
  1360.  
  1361.     This is an extremely important function!! Read the Warning paragraph.
  1362.  
  1363.    INPUTS
  1364.     void -
  1365.  
  1366.    RESULT
  1367.     void () -
  1368.  
  1369.    NOTE
  1370.     This function preserves ALL registers (Even the scratch ones)
  1371.  
  1372.    WARNING
  1373.     ° Don't forget to dmUnLockPrefs()!! Otherwise you would prevent the
  1374.     library from doing any dynamic changes in its list til next reboot
  1375.     which is not very nice..
  1376.  
  1377.    SEE ALSO
  1378.     dmUnLockPrefs()
  1379.  
  1380. datamaster.library/dmMatchName               datamaster.library/dmMatchName
  1381.  
  1382.    NAME
  1383.     dmMatchName -- Support function
  1384.  
  1385.    SYNOPSIS
  1386.     result = dmMatchName( UserString, Pattern );
  1387.     D0              A0      A1
  1388.  
  1389.     ULONG dmMatchName( STRPTR UserString, STRPTR Pattern );
  1390.  
  1391.    FUNCTION
  1392.     Provides an easy way to use dos.library/MatchPatternNoCase as it does
  1393.     all the hard job for you,such as allocating memory for the
  1394.     dos.library/ParsePatternNoCase routine that has to be called
  1395.     too,etc...
  1396.  
  1397.    INPUTS
  1398.     UserString - String to be compared.
  1399.  
  1400.     Pattern - Matching pattern.  See dos.library/ParsePattern() for the
  1401.         patterns definitions.
  1402.  
  1403.    RESULT
  1404.     result (D0) - returns zero **IF MATCHES** (may seem not so
  1405.         conventional but it's logical if you think it in
  1406.         assembler..."BEQ" happens when the Zero bit of the CCR is
  1407.         set...)
  1408.  
  1409.    NOTE
  1410.     Matching is case insensitive,as you had guessed.
  1411.  
  1412.    WARNING
  1413.     The UserString will be UPCASED by dos.library,so please,if you use
  1414.     this function in a recognizer,use something like a dmDupString() and
  1415.     DO NOT ALTER the initial data as you can't know wether it's
  1416.     "trashable" data loaded by a dmTestFile() call,or a **user-loaded
  1417.     data** he may legitimely expect to be kept untouched.
  1418.  
  1419.    BUGS
  1420.     Those of dos.library/MatchPatternNoCase,I suppose! (plus some more?)
  1421.  
  1422.    SEE ALSO
  1423.     dmRecognize(),dmRecognizePatt()
  1424.  
  1425. datamaster.library/dmQueryRecoList       datamaster.library/dmQueryRecoList
  1426.  
  1427.    NAME
  1428.     dmQueryRecoList -- OBSOLETE.  Information for this function is
  1429.     removed on purpose.
  1430.  
  1431.    SYNOPSIS
  1432.     dmQueryRecoList();
  1433.  
  1434.  
  1435.     void dmQueryRecoList (void);
  1436.  
  1437.    FUNCTION
  1438.     Use dmQueryRecoListNew() instead.
  1439.  
  1440.    SEE ALSO
  1441.     dmQueryRecoListNew()
  1442.  
  1443. datamaster.library/dmQueryRecoListNew    datamaster.library/dmQueryRecoListNew
  1444.  
  1445.    NAME
  1446.     dmQueryRecoListNew -- Get a list of the RECOGNIZERS currently in
  1447.     memory.  (V2)
  1448.  
  1449.    SYNOPSIS
  1450.     RecoList = dmQueryRecoListNew( Classes, Flags );
  1451.     D0                   D0    D1
  1452.  
  1453.     Struct RecoList *dmQueryRecoListNew( ULONG Classes, ULONG Flags );
  1454.  
  1455.    FUNCTION
  1456.  
  1457.     The library keeps a list of all the recognizer segments currently in
  1458.     memory.
  1459.  
  1460.     This list is sorted by PRIORITY,for efficiency.This function gives
  1461.     you back this same list,but ALPHA-SORTED.So you have the addresses of
  1462.     all the recognizers in memory,so you'll be able to get info on
  1463.     them,remove them from memory,etc, with the dedicated functions.
  1464.  
  1465.     you'll get in the structure:
  1466.  
  1467.     rl_NumRecos:the number of RECOGNIZERS in memory
  1468.  
  1469.     rl_RecoList:here is an address table pointing on all the first
  1470.     segments of the recognizers.
  1471.  
  1472.     The list ends with a zero LONG.
  1473.  
  1474.    INPUTS
  1475.     Classes - not used yet, set it to NULL.
  1476.  
  1477.     Flags - not used yet, set it to NULL.
  1478.  
  1479.    RESULT
  1480.     RecoList (D0) - RecoList structure.  (NULL if no memory)
  1481.  
  1482.    NOTE
  1483.     According to this library's 'philosophy',you may have more than one
  1484.     Recognizer *file/segment* for a SAME *filetype*.
  1485.  
  1486.     Getting direct SegmentAddresses of the recognizers will mainly be
  1487.     used for getting all the infos from the DMR_ tags (see the concerned
  1488.     support functions)
  1489.  
  1490.     [These addresses are REAL ones,NOT BCPL]
  1491.  
  1492.    WARNING
  1493.     You MUST use a dmLockPrefs() before calling this & an dmUnLockPrefs()
  1494.     when you finished your job with the addresses.
  1495.  
  1496.     Of course , don't forget to free the structure with a
  1497.     dmFreeRecoList().
  1498.  
  1499.    BUGS
  1500.     None known
  1501.  
  1502.    SEE ALSO
  1503.     dmQueryRecoNamesNew(),dmFreeRecoList(),dmGetDMR_Tag(),dmRemRecoAddr()
  1504.  
  1505. datamaster.library/dmQueryRecoNames      datamaster.library/dmQueryRecoNames
  1506.  
  1507.    NAME
  1508.     dmQueryRecoNames -- OBSOLETE.  Information for this function is
  1509.     removed on purpose.
  1510.  
  1511.    SYNOPSIS
  1512.     dmQueryRecoNames();
  1513.  
  1514.  
  1515.     void dmQueryRecoNames (void);
  1516.  
  1517.    FUNCTION
  1518.     Use dmQueryRecoNamesNew() instead.
  1519.  
  1520.    SEE ALSO
  1521.     dmQueryRecoNamesNew()
  1522.  
  1523. datamaster.library/dmQueryRecoNamesNew datamaster.library/dmQueryRecoNamesNew
  1524.  
  1525.    NAME
  1526.     dmQueryRecoNamesNew -- Get a list of the FILETYPES currently in
  1527.     memory.  (V2)
  1528.  
  1529.    SYNOPSIS
  1530.     RecoList = dmQueryRecoNamesNew( Classes, Flags );
  1531.     D0                D0     D1
  1532.  
  1533.     Struct RecoList *dmQueryRecoNamesNew( ULONG Classes, ULONG Flags );
  1534.  
  1535.    FUNCTION
  1536.     Similar to dmQueryRecoListNew(),but here you'll get an alpha-sorted
  1537.     list of all the FILETYPES NAMES...This gives you access to functions
  1538.     that deal with global filetypes names,not caring to know how many
  1539.     recognizers really correspond to a particular filetype.It's also
  1540.     cleaner when you want to display the filetypes.You could have the
  1541.     same result by calling dmQueryRecoListNew(),& then getting each
  1542.     recognizer's name by dmGetDMR_Tag().But you'd be obliged to handle
  1543.     all the multiple recognizer entries for a same filetype,leading you
  1544.     wether to check this,or print many times the same name...Hmmm...not
  1545.     so nice! So this function if for you.
  1546.  
  1547.     you'll get in the structure:
  1548.  
  1549.     rl_NumRecos:the number of RECOGNIZERS in memory
  1550.  
  1551.     rl_RecoList:here is an address table pointing on all the first
  1552.     segments of the recognizers.
  1553.  
  1554.     The list ends with a zero LONG.
  1555.  
  1556.    INPUTS
  1557.     Classes - not used yet, set it to NULL.
  1558.  
  1559.     Flags - not used yet, set it to NULL.
  1560.  
  1561.    RESULT
  1562.     RecoList (D0) - RecoList structure.  (NULL if no memory)
  1563.  
  1564.    NOTE
  1565.     According to this library's 'philosophy',you may have more than one
  1566.     Recognizer *file/segment* for a SAME *filetype*.
  1567.  
  1568.    WARNING
  1569.     You MUST use a dmLockPrefs() before calling this & an dmUnLockPrefs()
  1570.     when you finished manipulating the infos you got.
  1571.  
  1572.     Of course , don't forget to free the structure with a
  1573.     dmFreeRecoList().
  1574.  
  1575.    BUGS
  1576.     None known
  1577.  
  1578.    SEE ALSO
  1579.     dmQueryRecoListNew(),dmFreeRecoList(),dmRemRecoName()
  1580.  
  1581. datamaster.library/dmReadRecoFile        datamaster.library/dmReadRecoFile
  1582.  
  1583.    NAME
  1584.     dmReadRecoFile -- Loads a recognizer file
  1585.  
  1586.    SYNOPSIS
  1587.     Recognizer = dmReadRecoFile( FileName );
  1588.     D0                 A0
  1589.  
  1590.     APTR dmReadRecoFile( STRPTR FileName );
  1591.  
  1592.    FUNCTION
  1593.     Loads the recognizer but doesn't initialize it,nor link it to the
  1594.     list.
  1595.  
  1596.     It's just for an information purpose (from the DMR_ tags)
  1597.  
  1598.    INPUTS
  1599.     FileName - a filename,yes yes...  (Default path is set to
  1600.         LIBS:Recognizers/ )
  1601.  
  1602.    RESULT
  1603.     Recognizer (D0) - Address of the loaded segment (REAL addr,NOT BCPL).
  1604.         Returns zero if error.
  1605.  
  1606.    BUGS
  1607.     None known
  1608.  
  1609.    SEE ALSO
  1610.     dmFreeRecoFile(),dmAddRecoFile()
  1611.  
  1612. datamaster.library/dmRecognize               datamaster.library/dmRecognize
  1613.  
  1614.    NAME
  1615.     dmRecognize -- Analyse a portion of memory
  1616.  
  1617.    SYNOPSIS
  1618.     DM_Handle = dmRecognize( Addr, Size );
  1619.     D0             A0    D0
  1620.  
  1621.     APTR dmRecognize( APTR Addr, ULONG Size );
  1622.  
  1623.    FUNCTION
  1624.     Asks all the recognizers in memory (calling the DMR_Check tag
  1625.     function) to recognize the filetype of this data.If none succeeds,you
  1626.     will get a 'generic' filetype.
  1627.  
  1628.    INPUTS
  1629.     Addr - Address of data to be checked.
  1630.  
  1631.     Size - Size of the check...
  1632.  
  1633.    RESULT
  1634.     DM_Handle (D0) - address of a DM_Handle structure.In this
  1635.         structure,you'll find a pointer to the filetype in the
  1636.         dmh_String pointer.Each time a caller accesses one of the
  1637.         recognition functions,the library DUPLICATES the filetype
  1638.         name & creates the handle.  This uses a few bytes but it's
  1639.         very convenient,as caller gets an 'independent' string: it's
  1640.         a copy,so the recognizer which this string came from can be
  1641.         freed without problem while you still have a hand on YOUR
  1642.         string! Dont' forget to dmFreeDMHandle() the handle you
  1643.         got...    Starting with library V2, one additional field in the
  1644.         handle: - dmh_SubType: An additional subtype string, if
  1645.         available (else will be NULL).    For a more accurate
  1646.         recognition of the data.  PLEASE PROVIDE MATCHING TESTS FOR
  1647.         THIS STRING TOO!! This function will return NULL if memory
  1648.         can't be allocated for handle.
  1649.  
  1650.    EXAMPLE
  1651.  
  1652.  
  1653.     lea    data,a0
  1654.     move.l    #5000,d0
  1655.     CALLDM    dmRecognize
  1656.     tst.l    d0        ;<Get filetype name & print it for example>
  1657.     beq.s    .error
  1658.     move.l    d0,a4        ;get the valid DMhandle
  1659.     move.l    d0,handle
  1660.     move.l    dmh_String(a4),a0    ;get the filetype string...
  1661.     bsr    PrintTheString        ;print it with your routine
  1662.     tst.l    dmh_SubType(a4)
  1663.     beq.s    .nosubtype
  1664.     move.l    dmh_SubType(a4),a0    ;print subtype if available
  1665.     bsr    PrintTheString
  1666.  
  1667.    .nosubtype:
  1668.     ....                ;etc...
  1669.  
  1670.     move.l    handle,a0        ;don't forget to free the handle
  1671.     CALLDM    dmFreeDMHandle
  1672.  
  1673.     handle:    dc.l    0        ;store pointer to DM handle here.
  1674.     data:    (what is it I can't guess,but I hope the library will ;-)
  1675.  
  1676.    BUGS
  1677.     None known
  1678.  
  1679.    SEE ALSO
  1680.     dmRecognizePatt(),dmTestFile(),dmTestData(),dmFreeDMHandle()
  1681.  
  1682. datamaster.library/dmRecognizePatt       datamaster.library/dmRecognizePatt
  1683.  
  1684.    NAME
  1685.     dmRecognizePatt -- Analyze a name
  1686.  
  1687.    SYNOPSIS
  1688.     DM_Handle = dmRecognizePatt( Name );
  1689.     D0                 A0
  1690.  
  1691.     APTR dmRecognizePatt( STRPTR Name );
  1692.  
  1693.    FUNCTION
  1694.     Asks all the recognizers in memory (Matching all their DMR_Pattern
  1695.     lists) to recognize the filetype of this data.If none succeeds,you
  1696.     will get a 'generic' filetype.
  1697.  
  1698.    INPUTS
  1699.     Name - May be a real filename,or a dummy one,no matter,as only
  1700.         Pattern-matching will be done here.  Note:this name will be
  1701.         DOS/FileParted().
  1702.  
  1703.    RESULT
  1704.     DM_Handle (D0) - address of a DM_Handle structure.  See dmRecognize()
  1705.         for full information on the DMhandle.  This function will
  1706.         return NULL if memory can't be allocated for handle.
  1707.  
  1708.    EXAMPLE
  1709.  
  1710.  
  1711.     lea    data,a0
  1712.     CALLDM    dmRecognizePatt
  1713.     tst.l    d0        ;<Get filetype name & print it for example>
  1714.     beq.s    .error
  1715.     move.l    d0,a4        ;get the valid DMhandle
  1716.     move.l    d0,handle
  1717.     move.l    dmh_String(a4),a0    ;get the filetype string...
  1718.     bsr    PrintTheString        ;print it with your routine
  1719.     tst.l    dmh_SubType(a4)
  1720.     beq.s    .nosubtype
  1721.     move.l    dmh_SubType(a4),a0    ;print subtype if available
  1722.     bsr    PrintTheString
  1723.  
  1724.    .nosubtype:
  1725.     ....                ;etc...
  1726.     move.l    handle,a0        ;don't forget to free the handle
  1727.     CALLDM    dmFreeDMHandle
  1728.  
  1729.     handle:    dc.l    0        ;store pointer to DM handle here.
  1730.     data:    dc.b    "mod.survive",0    ;surely a "MUSIC-Ptk&Clones",no? Hmm...
  1731.  
  1732.    BUGS
  1733.     None known
  1734.  
  1735.    SEE ALSO
  1736.     dmRecognize(),dmTestFile(),dmTestData(),dmFreeDMHandle()
  1737.  
  1738. datamaster.library/dmRemRecoAddr         datamaster.library/dmRemRecoAddr
  1739.  
  1740.    NAME
  1741.     dmRemRecoAddr -- Frees a single recognizer from list.
  1742.  
  1743.    SYNOPSIS
  1744.     result = dmRemRecoAddr( address );
  1745.     D0            A0
  1746.  
  1747.     ULONG dmRemRecoAddr( APTR address );
  1748.  
  1749.    FUNCTION
  1750.     Calls the DMR_ExitRoutine of the recognizer & frees it from
  1751.     memory/list.
  1752.  
  1753.    INPUTS
  1754.     address - Address of the segment,obtained from the rl_RecoList table
  1755.         [filled by dmQueryRecoListNew() ],or from a single
  1756.         dmAddRecoFile(),dmGetRecoAddr() (may be NULL)
  1757.  
  1758.    RESULT
  1759.     result (D0) - zero if error (for the moment,failure only happens if
  1760.         somebody has locked the recognizerlist)
  1761.  
  1762.    NOTE
  1763.     ° No need to use a pair of dmLockPrefs() / dmUnLockPrefs()
  1764.  
  1765.     ° This function does NOT check the given address.Let's consider you
  1766.     make your code clean enough to give a correct pointer ;-)
  1767.  
  1768.    BUGS
  1769.     none known
  1770.  
  1771.    SEE ALSO
  1772.     dmAddRecoFile()
  1773.  
  1774. datamaster.library/dmRemRecoName         datamaster.library/dmRemRecoName
  1775.  
  1776.    NAME
  1777.     dmRemRecoName -- Frees a FILETYPE from list
  1778.  
  1779.    SYNOPSIS
  1780.     result = dmRemRecoName( Name );
  1781.     D0            A0
  1782.  
  1783.     ULONG dmRemRecoName( STRPTR Name );
  1784.  
  1785.    FUNCTION
  1786.     Finds & frees all the RECOGNIZERS of the list matching this FILETYPE
  1787.     name.
  1788.  
  1789.    INPUTS
  1790.     Name - Name of the filetype to free.  If string is "all" (case
  1791.         insensitive) then ALL the filetypes will be freed.  Note:In
  1792.         fact only the INTERNAL recognizers will remain.
  1793.  
  1794.    RESULT
  1795.     result (D0) - zero if error (for the moment,failure only happens if
  1796.         somebody has locked the recognizerlist)
  1797.  
  1798.    NOTE
  1799.     No need to dmLockPrefs() / dmUnLockPrefs()
  1800.  
  1801.    BUGS
  1802.     None known
  1803.  
  1804.    SEE ALSO
  1805.     dmAddRecoName()
  1806.  
  1807. datamaster.library/dmScanRecoDir         datamaster.library/dmScanRecoDir
  1808.  
  1809.    NAME
  1810.     dmScanRecoDir -- Flushes all current recognizers & loads contents of
  1811.     given directory
  1812.  
  1813.    SYNOPSIS
  1814.     result = dmScanRecoDir( DirName );
  1815.     D0            A0
  1816.  
  1817.     ULONG dmScanRecoDir( STRPTR DirName );
  1818.  
  1819.    FUNCTION
  1820.     Flushes all current external recognizers from memory,then scans the
  1821.     given directory for new recognizers.
  1822.  
  1823.    INPUTS
  1824.     DirName - Directory Path (may be NULL,so default LIBS:Recognizers/
  1825.         will be used)
  1826.  
  1827.    RESULT
  1828.     result (D0) - NULL if failure
  1829.  
  1830.    NOTE
  1831.     No need to use a pair of dmLockPrefs() / dmUnLockPrefs()
  1832.  
  1833.    BUGS
  1834.     None known
  1835.  
  1836.    SEE ALSO
  1837.     dmAddRecoDir()
  1838.  
  1839. datamaster.library/dmTestData            datamaster.library/dmTestData
  1840.  
  1841.    NAME
  1842.     dmTestData -- Determine the filetype of a given data buffer.  (V2)
  1843.  
  1844.    SYNOPSIS
  1845.     DM_Handle = dmTestData( Addr, Size, Flags, Name );
  1846.     D0            A0    D0    D1       A1
  1847.  
  1848.     APTR dmTestData( APTR Addr, ULONG Size, ULONG Flags, STRPTR Name );
  1849.  
  1850.    FUNCTION
  1851.     This is a more powerful function than dmRecognize() and
  1852.     dmRecognizePatt().
  1853.  
  1854.     It's main purpose is to be able to make both IN THE SAME TIME.    (if
  1855.     you give all the parameters).
  1856.  
  1857.     What would this do? Well, it calls both functions and keeps the
  1858.     "best" DM_Handle (i.e the one that is not "Generic" [=failure]).
  1859.  
  1860.     -> If Addr & Size are non-NULL, a dmRecognize() will be possible.
  1861.  
  1862.     -> If Name is non-NULL, a dmRecognizePatt() will be possible.
  1863.  
  1864.    INPUTS
  1865.     Addr - Address of the data to check.  (or NULL)
  1866.  
  1867.     Size - Size for the check...  (or NULL)
  1868.  
  1869.     Flags - See below
  1870.  
  1871.     Name - Optional filename (or NULL if not available) (The string will
  1872.         be DOS/FileParted() automatically)
  1873.  
  1874.    RESULT
  1875.     DM_Handle (D0) - address of a DM_Handle structure.  See dmRecognize()
  1876.         for full information on the DMhandle.  This function will
  1877.         return NULL if memory can't be allocated for handle.
  1878.  
  1879.    FLAGS
  1880.     Flags definitions:
  1881.  
  1882.         ° RECOF_PattPriority : Useful only when all parameters are
  1883.         set (means both dmRecognize() & dmRecognizePatt() will be
  1884.         used.)
  1885.  
  1886.         Normally "data" check beats "pattern" check.Setting this will
  1887.         reverse the situation.    Conclusion: if both "data" &
  1888.         "pattern" checks return a "non-generic" filetype, the
  1889.         "pattern" handle would here be used instead of the "data"'s.
  1890.         (can be useful in some cases, if you have recognizers with
  1891.         lots of pattern checks and poor data checks.).    User MUST
  1892.         have control on this.
  1893.  
  1894.         NOTE: Anyway, user HAS control on this, thanx to the DM_PattPri
  1895.         Env-variable! :)
  1896.  
  1897.    EXAMPLE
  1898.  
  1899.     example:
  1900.     ...
  1901.     lea    BufferAddr,a0
  1902.     move.l    #BufferSize,d0
  1903.     move.l    #RECOF_CheckData+RECOF_CheckPatt,d1
  1904.     lea    name,a1
  1905.     CALLDM    dmTestData
  1906.     tst.l    d0        ;<Get filetype name & print it for example>
  1907.     beq.s    .error
  1908.     move.l    d0,a0
  1909.     move.l    d0,handle
  1910.     ...            ;<use,print,etc the filetype string>
  1911.     move.l    handle,a0    ;don't forget to free the handle
  1912.     CALLDM    dmFreeDMHandle
  1913.  
  1914.     handle:    dc.l    0
  1915.     name:    dc.b    "DH1:Mydir/BlahBlah/file",0
  1916.  
  1917.    NOTE
  1918.     THAT is a nice & simple function (to use I mean ;-)),don't you think?
  1919.  
  1920.    BUGS
  1921.     None known
  1922.  
  1923.    SEE ALSO
  1924.     dmRecognize(),dmRecognizePatt(),dmTestFile()
  1925.  
  1926. datamaster.library/dmTestFile            datamaster.library/dmTestFile
  1927.  
  1928.    NAME
  1929.     dmTestFile -- Determine the filetype of a given file.
  1930.  
  1931.    SYNOPSIS
  1932.     DM_Handle = dmTestFile( Name, Size, Flags );
  1933.     D0            A0    D0    D1
  1934.  
  1935.     APTR dmTestFile( STRPTR Name, ULONG Size, ULONG Flags );
  1936.  
  1937.    FUNCTION
  1938.     Gets the file type,by any means!
  1939.  
  1940.    INPUTS
  1941.     Name - Name of the file to analyze.Depending of the flags given,this
  1942.         string may be just a name,or a real existing path.Anyway the
  1943.         string will be DOS/FileParted() so you won't have to bother
  1944.         to do it.
  1945.  
  1946.     Size - Loading size for filetype-analyzing.Needed only if the
  1947.         RECOB_CheckData bit is set.  (-1 means whole file)
  1948.  
  1949.     Flags - See flags
  1950.  
  1951.    RESULT
  1952.     DM_Handle (D0) - address of a DM_Handle structure.  See dmRecognize()
  1953.         for full information on the DMhandle.  This function will
  1954.         return NULL if memory can't be allocated for handle.
  1955.  
  1956.    FLAGS
  1957.     Flags definitions:
  1958.  
  1959.         ° RECOF_CheckData: verify REALLY the data,so will need to
  1960.         load a part of the file.
  1961.  
  1962.         ° RECOF_CheckPatt: verify only the filename pattern.Surely
  1963.         much faster than Checkdata but also less accurate ;(.Can be
  1964.         used for 'virtual' filenames.
  1965.  
  1966.         ° RECOF_XPKload : use XPKRead() instead of the 'classic' DOS
  1967.         function.  So,no need to be an xdata client for your
  1968.         application.The obvious advantage of this is to recognize
  1969.         data even if the file is xpk-crunched! It's always a pity
  1970.         when you get a result such as 'xpk packed' or 'unknown' :-)
  1971.         This makes it better...
  1972.  
  1973.         ° RECOF_PattPriority : Useful only if RECOF_CheckData &
  1974.         RECOF_CheckPatt are both set.
  1975.  
  1976.         Normally "data" check beats "pattern" check.Setting this will
  1977.         reverse the situation.    (can be useful in some cases, if you
  1978.         have recognizers with lots of pattern checks and poor data
  1979.         checks.).  User MUST have control on this.
  1980.  
  1981.         Note:RECOB_CheckData & RECOB_CheckPatt bits may be both
  1982.         set;in that case dmRecognize() will be called first,& if it
  1983.         'fails' (means it gets a 'Generic' filetype),then
  1984.         dmRecognizePatt() will be used.  Conclusion: if both "data" &
  1985.         "pattern" checks return a "non-generic" filetype, the
  1986.         "pattern" handle would here be used instead of the "data"'s.
  1987.  
  1988.    EXAMPLE
  1989.  
  1990.     ;This will xpk unpack 5000 bytes of the file
  1991.     ;do a dmRecognize() on them,& if it gets a 'generic' filetype,
  1992.     ;then a dmRecognizePatt() will be tried.
  1993.     example1:
  1994.     ...
  1995.     lea    name,a0
  1996.     move.l    #5000,d0
  1997.     move.l    #RECOF_CheckData+RECOF_CheckPatt+RECOF_XPKload,d1
  1998.     CALLDM    dmTestFile
  1999.     tst.l    d0        ;<Get filetype name & print it for example>
  2000.     beq.s    .error
  2001.     move.l    d0,a0
  2002.     move.l    d0,handle
  2003.     ...            ;<use,print,etc the filetype string>
  2004.     move.l    handle,a0    ;don't forget to free the handle
  2005.     CALLDM    dmFreeDMHandle
  2006.  
  2007.     handle:    dc.l    0
  2008.     name:    dc.b    "DH1:Mydir/BlahBlah/file",0
  2009.  
  2010.     ;This will only analyze the name pattern,& will
  2011.     ;of course get a "Icon" filetype
  2012.     example2:
  2013.     ...
  2014.     lea    name,a0
  2015.     move.l    #RECOF_CheckPatt,d1
  2016.     CALLDM    dmTestFile
  2017.     tst.l    d0        ;<Get filetype name & print it for example>
  2018.     beq.s    .error
  2019.     move.l    d0,a0
  2020.     move.l    d0,handle
  2021.     ...
  2022.     move.l    handle,a0    ;don't forget to free the handle
  2023.     CALLDM    dmFreeDMHandle
  2024.  
  2025.     handle:    dc.l    0
  2026.     name:    dc.b    "ReallyDummy:DummyDummyDummy.info",0
  2027.  
  2028.    NOTE
  2029.     THAT is a nice & simple function (to use I mean ;-)),don't you think?
  2030.  
  2031.    BUGS
  2032.     None known
  2033.  
  2034.    SEE ALSO
  2035.     dmRecognize(),dmRecognizePatt(),dmTestData()
  2036.  
  2037. datamaster.library/dmUnLockPrefs         datamaster.library/dmUnLockPrefs
  2038.  
  2039.    NAME
  2040.     dmUnLockPrefs -- Indicate that user finished using info of
  2041.     recognizers.
  2042.  
  2043.    SYNOPSIS
  2044.     void = dmUnLockPrefs( void );
  2045.                   
  2046.  
  2047.     VOID dmUnLockPrefs( VOID void );
  2048.  
  2049.    FUNCTION
  2050.     Decreases by one the dmb_LockNest counter of
  2051.     DatamasterBase,indicating that user finished reading/using
  2052.     informations in the recognizers (mainly tags)
  2053.  
  2054.     This is an extremely important function!! Read the Warning paragraph.
  2055.  
  2056.    INPUTS
  2057.     void -
  2058.  
  2059.    RESULT
  2060.     void -
  2061.  
  2062.    NOTE
  2063.     This function preserves ALL registers (Even the scratch ones)
  2064.  
  2065.    WARNING
  2066.     ° Don't forget to dmUnLockPrefs()!! Otherwise you would prevent the
  2067.     library from doing any dynamic changes in its list til next reboot
  2068.     which is not very nice..
  2069.  
  2070.    SEE ALSO
  2071.     dmLockPrefs()
  2072.  
  2073.